Connections

Features and Improvements

OpenCPN can use a number of different data sources for navigation and environment.

Connection to such a source is set up using this interface.

This applies to navigation data to OpenCPN itself as well as navigation and environment data to plugins.

Data sources can be connected using different types of connections. It can be serial (USB, RS232) or network. Networks can also be available with different variants such as internet protocol-IP (UDP, TCP) or CanBus for some operating systems.

Each data source can use different types of standards to transmit information. OpenCPN supports receiving data according to the following standards:
NMEA0183 (N0183), NMEA2000 (N2k) and SignalK (SK).

OpenCPN has a built-in multiplexer where all incoming and outgoing data is distributed.
Data from OpenCPN and plugins in the N0183 format can be sent out to various external users. For example, an autopilot.
The multiplexer can also filter input and output of N0183 data.

OpenCPN use a prioritization function for navigation data. Only one source of position data is used at a time. “First in, first out” but it can be adjusted by the user. See more details below.

Set-up of incoming and outgoing data from different sources and to consumers is managed using the connection window.
Plugins can also internally send data to OpenCPN multiplexer. One example could be VDR, voyage data recorder. Such data is not handled by this interface.

For further details see the table of contents below.

Contents

Connections Window
Example Data Connections Window
Adjust data priority scheme
Filter NMEA Course and Speed Data
Show NMEA Debug Window
Data Connections - Add and Remove
Add a Serial Connection
Linux Serial Connections
Add a Network Connection
Network GPSD connection
Connections Filter
Input Filtering
Output Filtering
Connection Notes
Sending an Active Route to an Autopilot
Sending Routes and Waypoints to a GPS
Broadcast and Multicast

Connections Window

All this is different from the logic in earlier versions of OpenCPN. From version 3.2, there is no defined “autopilot” port. The autopilot is simply connected to any available output- enabled data-stream, and gets everything on the bus, subject to user specified output filtering. There is no specific “shared” AIS and GPS port, as all ports are shared.


The key point to keep in mind with this new setup is the complete orthogonality between message sources, message destinations, and transport media. All messages come and go from an internal “bus”, and all internal modules have access to all messages. Any message can be received, and possibly re-transmitted according to the configuration established. If the messages get onto the bus,

OpenCPN will do the right thing. For example, if it is an AIS message, the AIS module will get the message and act accordingly. Plugins also get all messages.

Example Data Connections Window

To get a taste of what can be done, we start with a lab scenario. In the screen-shot above, four Data Ports are enabled.

Note that the connections are automatically sorted in order of the priority setting The picture is from a Linux computer, but the receiving box is an Win XP. Both boxes are configured to use the same broadcasting address '192.168.0.255' on the local network, using the default 10110 port. Note that UDP, and not TCP, is used. OpenCPN on the XP box receives and shows all info from the three first ports and even data from the VDR plugin, if it's running. All input sources are merged together and available to transmit to an external computer. Every computer on-board can be used as a repeater to the main box!

Note that in this scenario the UDP connection is output only. In previous releases of OpenCPN all UDP data connections would read data as well as write. This is a possible configuration in the current release but neither required nor generally desirable. If a broadcast connection is read/write, all data written will be read back leading to the potential for data loops.

There is no advantage to using a broadcast address on the local network with just a few computers. It's as easy to just specify the addresses of the receiving computers as outgoing connections on the transmitting computer. The “receivers” specify the “transmitter” as address for a connection.

In real life, a common setup will include input from GPS, AIS and output to an Autopilot. If your GPS produces GPRMC, then this will be automatically shipped to the autopilot.

Filter NMEA Course and Speed Data

Providing a rolling average of COG/SOG, with configurable sampling period. This feature is useful, for example, if you find that course and speed from the gps is varying erratically due to the sea state. The Dashboard plugin is not affected by this setting - COG and SOG are updated about once per second.

Show NMEA Debug Window

If you check this box you will get a window that shows the NMEA data sentences coming into or going out from OpenCPN. In the picture above we can see the color-coding at work. Messages in red could occur as well, and indicates a transmit error. Connections Priority change messages, will also be printed to the NMEA Debug Window. The reason that AIVDM messages are both dropped and appear as “Output message”, is that there is more than one source for this message, and the filter just applies to one source.

Have a look at the page NMEA Sentences to see which messages are understood. OpenCPN generally does not care about the Talker ID, the first two letters in the message type. $GPGGA above, is the talker GP = the gps, sending a GGA = position message, for example. At the end of each sentence there is a “*” followed by a calculated checksum.

To see all messages it's important to close the Options dialog completely, while leaving the NMEA Debug window open. The ECAPB sentences etc, will not appear while the Connections dialog box is open as autopilot output is disabled during this time.

Known issues: The pause button only works if the main Options dialog is closed. In Linux, the debug window can only be closed by unticking the Show NMEA Debug Window box, unless the the main Options dialog is closed.

If there are NMEA sentences in the debug window, then OpenCPN has opened the port set in the Data Connections. Note that the source of each NMEA sentence is printed after the time stamp o each line. If your GPS port is configured, and there is no “red” boat, then the only reasons are: no gps fix or wrong sentence configuration from the GPS.

Messages originating from GPSD or the VDR (Voyage Data Recorder plugin) will also show up in the debug window.

For simple NMEA data stream debugging, add the following to your opencpn.ini file:Under [Settings] add a line DebugNMEA=1500 This will provide up to 1500 debug messages pertaining to NMEA traffic to the opencpn.log.

Format uploads for FurunoGP3Xinputfiltering: If the special Furuno gps protocol is needed, tick this box. The reason is that Furuno uses their own version of NMEA for uploading routes. Furuno GPS users take note. It is now allowed to use a numeric, two digit OpenCPN route name (e.g. 10, 21, etc).

Use GarminGRMN (Host) mode for uploads. Make sure that this box is ticked, if you have a Garmin GPS. The reason for this is that Garmin units cannot accept route uploads via standard NMEA0183. This is a “design feature” of all Garmin receivers.

Use magnetic bearings in output sentence ECAPB. Some autopilots, among them Simrad, require navigational bearings, contained in the APB sentence, to be transmitted as Magnetic bearings rather than as True bearings, OpenCPNs default.

Data Connections - Add and Remove

Two Buttons “Add Connections” and “Remove Connections”, to the right of the Connections window are the key to this whole tab.

The enable choice at the start of each connection line, is handy to organize connections, but still only use those that are needed for the moment. Tick or un-tick, and then press “Apply”, to activate the setting.

A connection can be used for input and output at the same time, with the reservation that they have to use the same Baud rate. For more details, read on.

When pressing “Add Connections” two basic choices are given, a serial or a network connection.

Add a Serial Connection

DataPort: Pick a port by pressing the \/ o the right side of the field. If the port you are looking for does not appear in the selection, write the correct port yourself in this field. [2021-05-13 Two users (1, 2) have reported problems with manual entry of the com port that were corrected by using the drop down selection of the same port]

Baud Rate: This is normally 4800 for GPS and 38400 for AIS, but check the documentation for the connected device. It's important to get this right and not just guess.

Protocol: For future use, as only NMEA 0183 works, for now.

Priority: Higher number equals Higher priority. The priority is set for each NMEA sentence individually. As long as a higher priority stream is available it's used. If this fails the next stream in line, with lower priority, kicks in and is used, until a higher priority stream appears. The present filter does not handle the case where, for example position messages, are received from different sentences.As an example, GPGLL and GPRMC both transmits the position information. The last received of either message will be used.

Control Checksum. At the end of each NMEA sentence is a checksum, that makes sure that sentences are correctly received. This box is ticked by default, as OpenCPN calculates the checksum and compares it to the received checksum. Only sentences with a valid checksum are passed through. Un-ticking may help, if an application calculates checksums incorrectly or if the checksums are missing.

Use Garmin(GRMN) mode for input: Make sure that this box is ticked, if you have a Garmin GPS set to this mode. The reason is that Garmin uses their own serial protocol.

Receive input on this Port Greyed out here as it only applies to a network connection. see more below.

Output on this port (as Autopilot or NMEA repeater ): Tick this box if the connection will be used for output. A common case is sending NMEA to an Autopilot. * Talker ID solves the problem where some “temperamental” devices, which should accept given sentences irrespective of the talker ID, in fact only accept for example GPRMC and not ECRMC

APB bearing precision is greyed out unless “Output on this port” is checked. APB is the NMEA sentence “Autopilot Sentence 'B'”. The precision can be set to between 0 and 4 decimals, were 3 is the default. Some autopilots requires a different precision than the default, to work. Check your AP documentation.

Linux Serial Connections

Make sure that you belong to the “dialout” group. To find out, run the “$groups” command. If you're not in “dialout”, add yourself with the command “$sudo usermod -a -G dialout $USER”. Logout of your current session for group changes to take effect. Check this straight away, it will save you from frustration later on. If there is a problem connecting the GPS to a physical port, such as /dev/ttyS0, the reason is probably that you don't belong to “dialout”. OpenCPN will display a warning, once per session, if you try to configure a serial connection, or starts the program with an active serial connection, and don't belong to the right group.

group.jpeg

Red Hat based Linux versions are using the “uucp” group. Check what applies to your version of Linux, by using the return from the command stat -c %G `ls /dev/*|grep -m1 tty[A-Z,a-z][0] If the return is “root”, upgrade to a contemporary Linux version.

Add a Network Connection

Protocol Choices: TCP, UDP or GPSD

TCP

A “connection-oriented” protocol which provides a reliable link between two network endpoints. TCP ensures that any network packets lost in transit are re-transmitted. Internet AIS servers normally accept TCP connections as do many serial-to-network/wifi devices.

To make a connection to a remote TCP server, enter its IP address or hostname in the “Address” box and the TCP port on which the server listens in the “DataPort” box. Many devices use a non-standard TCP port rather than OpenCPN's standard 10110, so do check the server's documentation.

If “0.0.0.0” is entered in the Address box, OpenCPN will act as a TCP server accepting a connection from a remote TCP client. OpenCPN will listen on all its host computer's network interfaces for TCP connections to the port specified in the “DataPort” field. There should normally be no reason to select a “DataPort” value other than the standard 10110 unless multiple servers are required:

UDP

A method of transmitting data as simple “datagrams” without negotiating a connection between two endpoints. It involves no detection and retransmission of data lost in the network. Within a small home/boat network such data loss should not normally occur and in any case, NMEA data is generally updated by “talkers” on a regular basis. Unlike TCP which involves a connection between two endpoints, UDP data may be received by many “listeners”.

An OpenCPN UDP data connection will listen for data destined for the specified DataPort on any system interface or the broadcast address of any connected network.

For more information about broadcast and multicast, see Broadcast and Multicast below.

GPSD

A Unix/Linux gps server, which means that several different applications can share one gps receiver. Linux users have the choice between using serial or GPSD connections for their gps input.

Port: The port to connect to on the network address. The default port for UDP is 10110. Port 10110 is designated by IANA for “NMEA-0183 Navigational Data”. There should not be any reason to change this port, but it is possible. See below. The default port for GPSD is 2947. Do not change this!

Network GPSD connection

When connecting to GPSD, running on your local computer, use the settings shown above.

Connections Filter

For each source line in the data connection windows, it's possible to specify exactly which NMEA sentences to receive, and which ones to drop. Similarly it's possible to control exactly which sentences to send out to, for example, an autopilot.

The applied filters for each connection are stated in in the “Filters” column in the Data Connection window. The default for a connection is no filters at all. * The set filters applies to both the core program and the plugins.

Filtering can be observed in real time, through color coding in the Debug Window.

Accept only sentences: Either base your filtering on stating which sentences to accept or which to ignore.

Ignore sentences: Same as above. To select filters press the button. The dialog below becomes available.

A lot of NMEA sentences are listed. You may have to add a NMEA sentence that is not in the list. Just tick the box to select a sentence. “Select All” or “Clear All” are also available. For sentences not listed press “Add”, and enter a new NMEA sentence.

Your entry must conform to these rules.

When you are finished, press “OK”, your new entry will appear at the bottom of the list of NMEA sentences to filter. It will already be ticked, so just press “OK” until you are back in the original Connections tab. Now press “Apply”. The implemented filtering should now be visible on the connection line. For more, see below

Receive input on this port: This box should be ticked if you want to receive receive data on this connection. If the connection will only be used to output to other devices it should not be ticked. If you wish to broadcast UDP data for consumption by other devices or programs, leaving this box unticked will save you having to worry setting the priority of the connection to avoid data loops.

Output on this port (as Autopilot or NMEA repeater ): Tick this box if the connection will be used for output. A common case is sending NMEA to an Autopilot. * APB bearing precision is greyed out unless “Output on this port” is checked. APB is the NMEA sentence “Autopilot Sentence 'B'”. The precision can be set to between 0 and 4 decimals, were 3 is the default. Some autopilots requires a different precision than the default, to work. Check your AP documentation and see Note below.

OpenCPN creates and sends the NMEA ECRMB and ECRMC sentences to the A/P output port when a route is activated. If variation is not otherwise present, OpenCPN includes variation, coming from the WMM plugin, if installed and enabled.

Note: The “APB bearing precision” (or NMEAAPBPrecision in Opencpn.ini file) setting is set in the Connections settings page for connections that have outgoing messages. The precision is applied in the src/nmea0183/ apb.cpp file and is applied to:

FIXME {{opencpn:manual:action-filter.png?nolink&28×30}}

Input Filtering

Some examples to illustrate how things works.

Accepting the filter above leads to this in the filter column on the connection line:


If “Ignore sentences” is marked instead, the line looks like this:

Output Filtering

Similar to input filtering above.

Transmitting three sentences.

Another Example of Output Filtering

Feature: Can now select the NMEA talker ID of sentences output by OpenCPN on a given port.

Situation: OpenCPN (correctly) outputs its NMEA sentences with the “EC” talker ID as is normal and expected behavior (see below).

Problem : Some “temperamental” devices which should accept given sentences irrespective of the talker ID in fact only accept for example GPRMC and not ECRMC.

Example: An Icom VHF is a such example. and because the multiplexer has been set to give precedence to nav info provided by OpenCPN, rather than the GPS, the result is that when OpenCPN is driving the autopilot, the VHF does not receive any position anymore for its DSC feature. Safety-wise, this is not desirable.

Solution: Being able to either change the ECRMC sentences into GPRMC, or duplicate ECRMC on the output port should solve the issue.

AutoPilot Compatibility with respect to heading

- From O's point of view, the basic sentence the AP needs is RMB (It already contains the XTE information), most AP work with jut this sentence being output. - If this is not enough, and especially if the pilot is Simrad / B&G with simnet, APB must be added so that the gateway adds the PGN “heading / track control). Cruiser's Forum has an excellent thread discussion testing a N2K AP, using various devices, a summary post #106 but the entire thread is informative.